<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.06">

<base target="main">
<script language="JavaScript">
<!-- Begin
function loadTop(url) {
  parent.location.href= url;
}
// -->
</script><link rel="stylesheet" type="text/css" href="cil.css">
<title>How to Use CIL</title>
</head>
<body >
<a href="cil004.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="ciltoc.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="attributes.html"><img src="next_motif.gif" alt="Next"></a>
<hr>
<h2 id="sec6" class="section">5&#XA0;&#XA0;How to Use CIL</h2>
<p><a id="sec-cil"></a></p><p>There are two predominant ways to use CIL to write a program analysis or
transformation. The first is to phrase your analysis as a module that is
called by our existing driver. The second is to use CIL as a stand-alone
library. We highly recommend that you use <span style="font-family:monospace">cilly</span>, our driver. </p>
<h3 id="sec7" class="subsection">5.1&#XA0;&#XA0;Using <span style="font-family:monospace">cilly</span>, the CIL driver</h3>
<p>The most common way to use CIL is to write an Ocaml module containing your
analysis and transformation, which you then link into our boilerplate
driver application called <span style="font-family:monospace">cilly</span>. <span style="font-family:monospace">cilly</span> is a Perl script that
processes and mimics <span style="font-family:monospace">GCC</span> and <span style="font-family:monospace">MSVC</span> command-line arguments and then
calls <span style="font-family:monospace">cilly.byte.exe</span> or <span style="font-family:monospace">cilly.asm.exe</span> (CIL&#X2019;s Ocaml executable). </p><p>An example of such module is <span style="font-family:monospace">logwrites.ml</span>, a transformation that is
distributed with CIL and whose purpose is to instrument code to print the
addresses of memory locations being written. (We plan to release a
C-language interface to CIL so that you can write your analyses in C
instead of Ocaml.) See Section&#XA0;<a href="ext.html#sec-Extension">8</a> for a survey of other example
modules. </p><p>Assuming that you have written <span style="font-family:monospace">/home/necula/logwrites.ml</span>, 
here is how you use it: </p><ol class="enumerate" type=1><li class="li-enumerate">Modify <span style="font-family:monospace">logwrites.ml</span> so that it includes a CIL &#X201C;feature
descriptor&#X201D; like this: 
<pre class="verbatim">let feature : featureDescr = 
  { fd_name = "logwrites";              
    fd_enabled = ref false;
    fd_description = "generation of code to log memory writes";
    fd_extraopt = [];
    fd_doit = 
    (function (f: file) -&gt; 
      let lwVisitor = new logWriteVisitor in
      visitCilFileSameGlobals lwVisitor f)
  } 
</pre>The <span style="font-family:monospace">fd_name</span> field names the feature and its associated
command-line arguments. The <span style="font-family:monospace">fd_enabled</span> field is a <span style="font-family:monospace">bool ref</span>.
&#X201C;<span style="font-family:monospace">fd_doit</span>&#X201D; will be invoked if <span style="font-family:monospace">!fd_enabled</span> is true after
argument parsing, so initialize the ref cell to true if you want
this feature to be enabled by default.<p>When the user passes the <span style="font-family:monospace">--dologwrites</span>
command-line option to <span style="font-family:monospace">cilly</span>, the variable associated with the
<span style="font-family:monospace">fd_enabled</span> flag is set and the <span style="font-family:monospace">fd_doit</span> function is called
on the <span style="font-family:monospace">Cil.file</span> that represents the merger (see Section&#XA0;<a href="merger.html#sec-merger">13</a>) of
all C files listed as arguments. </p></li><li class="li-enumerate">Invoke <span style="font-family:monospace">configure</span> with the arguments
<pre class="verbatim">./configure EXTRASRCDIRS=/home/necula EXTRAFEATURES=logwrites
</pre><p>This step works if each feature is packaged into its own ML file, and the
name of the entry point in the file is <span style="font-family:monospace">feature</span>.</p><p>An alternative way to specify the new features is to change the build files
yourself, as explained below. You&#X2019;ll need to use this method if a single
feature is split across multiple files.</p><ol class="enumerate" type=a><li class="li-enumerate">
Put <span style="font-family:monospace">logwrites.ml</span> in the <span style="font-family:monospace">src</span> or <span style="font-family:monospace">src/ext</span> directory. This
will make sure that <span style="font-family:monospace">make</span> can find it. If you want to put it in some
other directory, modify <span style="font-family:monospace">Makefile.in</span> and add to <span style="font-family:monospace">SOURCEDIRS</span> your
directory. Alternately, you can create a symlink from <span style="font-family:monospace">src</span> or
<span style="font-family:monospace">src/ext</span> to your file.</li><li class="li-enumerate">Modify the <span style="font-family:monospace">Makefile.in</span> and add your module to the 
<span style="font-family:monospace">CILLY_MODULES</span> or
<span style="font-family:monospace">CILLY_LIBRARY_MODULES</span> variables. The order of the modules matters. Add
your modules somewhere after <span style="font-family:monospace">cil</span> and before <span style="font-family:monospace">main</span>.</li><li class="li-enumerate">If you have any helper files for your module, add those to
the makefile in the same way. e.g.:<pre class="verbatim">CILLY_MODULES = $(CILLY_LIBRARY_MODULES) \
                myutilities1 myutilities2 logwrites \
                main
</pre><p>Again, order is important: <span style="font-family:monospace">myutilities2.ml</span> will be able to refer
to Myutilities1 but not Logwrites. If you have any ocamllex or ocamlyacc
files, add them to both <span style="font-family:monospace">CILLY_MODULES</span> and either <span style="font-family:monospace">MLLS</span> or
<span style="font-family:monospace">MLYS</span>.</p></li><li class="li-enumerate">Modify <span style="font-family:monospace">main.ml</span> so that your new feature descriptor appears in
the global list of CIL features. 
<pre class="verbatim">let features : C.featureDescr list = 
  [ Logcalls.feature;
    Oneret.feature;    
    Heapify.feature1;  
    Heapify.feature2;
    makeCFGFeature; 
    Partial.feature;
    Simplemem.feature;
    Logwrites.feature;  (* add this line to include the logwrites feature! *)
  ] 
  @ Feature_config.features 
</pre><p>Features are processed in the order they appear on this list. Put
your feature last on the list if you plan to run any of CIL&#X2019;s
built-in features (such as makeCFGfeature) before your own.</p></li></ol><p>Standard code in <span style="font-family:monospace">cilly</span> takes care of adding command-line arguments,
printing the description, and calling your function automatically. 
Note: do not worry about introducing new bugs into CIL by adding a single
line to the feature list. </p></li><li class="li-enumerate">Now you can invoke the <span style="font-family:monospace">cilly</span> application on a preprocessed file, or
instead use the <span style="font-family:monospace">cilly</span> driver which provides a convenient compiler-like
interface to <span style="font-family:monospace">cilly</span>. See Section&#XA0;<a href="cil007.html#sec-driver">7</a> for details using <span style="font-family:monospace">cilly</span>.
Remember to enable your analysis by passing the right argument (e.g.,
<span style="font-family:monospace">--dologwrites</span>). </li></ol>
<h3 id="sec8" class="subsection">5.2&#XA0;&#XA0;Using CIL as a library</h3>
<p>CIL can also be built as a library that is called from your stand-alone
application. Add <span style="font-family:monospace">cil/src</span>, <span style="font-family:monospace">cil/src/frontc</span>, <span style="font-family:monospace">cil/obj/x86_LINUX</span>
(or <span style="font-family:monospace">cil/obj/x86_WIN32</span>) to your Ocaml project <span style="font-family:monospace">-I</span> include paths.
Building CIL will also build the library <span style="font-family:monospace">cil/obj/*/cil.cma</span> (or
<span style="font-family:monospace">cil/obj/*/cil.cmxa</span>). You can then link your application against that
library. </p><p>You can call the <span style="font-family:monospace">Frontc.parse: string -&gt; unit -&gt; Cil.file</span> function with
the name of a file containing the output of the C preprocessor.
The <span style="font-family:monospace">Mergecil.merge: Cil.file list -&gt; string -&gt; Cil.file</span> function merges
multiple files. You can then invoke your analysis function on the resulting
<span style="font-family:monospace">Cil.file</span> data structure. You might want to call
<span style="font-family:monospace">Rmtmps.removeUnusedTemps</span> first to clean up the prototypes and variables
that are not used. Then you can call the function <span style="font-family:monospace">Cil.dumpFile:
cilPrinter -&gt; out_channel -&gt; Cil.file -&gt; unit</span> to print the file to a
given output channel. A good <span style="font-family:monospace">cilPrinter</span> to use is
<span style="font-family:monospace">defaultCilPrinter</span>. </p><p>Check out <span style="font-family:monospace">src/main.ml</span> and <span style="font-family:monospace">bin/cilly</span> for other good ideas
about high-level file processing. Again, we highly recommend that you just
our <span style="font-family:monospace">cilly</span> driver so that you can avoid spending time re-inventing the
wheel to provide drop-in support for standard <span style="font-family:monospace">makefile</span>s. </p><p>Here is a concrete example of compiling and linking your project against
CIL. Imagine that your program analysis or transformation is contained in
the single file <span style="font-family:monospace">main.ml</span>. </p><pre class="verbatim">$ ocamlopt -c -I $(CIL)/obj/x86_LINUX/ main.ml
$ ocamlopt -ccopt -L$(CIL)/obj/x86_LINUX/ -o main unix.cmxa str.cmxa \ 
        $(CIL)/obj/x86_LINUX/cil.cmxa main.cmx
</pre><p>The first line compiles your analysis, the second line links it against CIL
(as a library) and the Ocaml Unix library. For more information about
compiling and linking Ocaml programs, see the Ocaml home page
at <a href="javascript:loadTop('http://caml.inria.fr/ocaml/')">http://caml.inria.fr/ocaml/</a>. </p><p>In the next section we give an overview of the API that you can use
to write your analysis and transformation. </p>
<hr>
<a href="cil004.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="ciltoc.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="attributes.html"><img src="next_motif.gif" alt="Next"></a>
</body>
</html>
